Session Management

Introduction

PicketBox provides a robust session management framework that works generically without any dependence on the web container. You can use it in non-web environments if you please.

The sessions can be stored using different approachs:

Local in-memory cache or a near cache;
Local File based storage.
Distributed in-memory cache;
Custom stores.

PicketBox Session Management also provides ways to listen for some specific session related events like creation, invalidation, expiration, set attributes, etc.

How it works ?

images/author/download/attachments/53117631/session_mgmt.png

Session Manager

The org.picketbox.core.session.SessionManager is responsible for create, retrieve, remove and update sessions. Only the SessionManager knows how to create PicketBoxSession instances based on the current authenticated PicketBoxSubject and how to use a SessionStore to maintain/store the sessions.

/**
 * <p>
 * Session managers are responsible for managing the {@link PicketBoxSession} instances. Session managers usually delegate the
 * storage of sessions to {@link SessionStore} implementations.
 * </p>
 *
 * @author Anil Saldhana
 * @author <a href="mailto:psilva@redhat.com">Pedro Silva</a>
 *
 * @see SessionStore
 */
public interface SessionManager extends PicketBoxLifecycle {

    /**
     * Construct a session
     *
     * @param authenticatedSubject
     * @return
     */
    PicketBoxSession create(PicketBoxSubject authenticatedSubject);

    /**
     * <p>
     * Retrieve a {@link PicketBoxSession} using its {@link SessionId}.
     * </p>
     *
     * @param id
     * @return
     */
    PicketBoxSession retrieve(SessionId<? extends Serializable> id);

    /**
     * <p>
     * Removes a {@link PicketBoxSession}.
     * </p>
     * @param session
     */
    void remove(PicketBoxSession session);

    /**
     * <p>
     * Updates a {@link PicketBoxSession}.
     * </p>
     *
     * @param session
     */
    void update(PicketBoxSession session);
}

Session Storage

Sessions need to be stored somewhere for further use. For example, If you are using PicketBox with a web application the store will probably be the user's http session. Or if you are using PicketBox with a Java SE application the store will probably be a local cache in your VM.

PicketBox provides following categories of session stores:

Local in-memory store
Local file based store
Distributable in-memory store using Infinispan. Or a near cache with a ClusterCacheLoader, for example.
Custom stores

How to use ?

Configuration

To configure the PicketBox Session Management you can use the Configuration API as following:

ConfigurationBuilder builder = new ConfigurationBuilder();

builder
    .sessionManager()
        .inMemorySessionStore()
        .sessionTimeout(1);


// others configurations

The above example uses the in-memory session store. If you want to use the File Based session storage, do the following:

ConfigurationBuilder builder = new ConfigurationBuilder();

builder
    .sessionManager()
        .fileSessionStore()
        .sessionTimeout(1);


// others configurations

In this example, the filename where the sessions are stored will be called "PBOXSESSION.DAT"

Use .fileSessionStore(myFileName) api in above, if you want to change the filename.

You can also configure your own session store implementation. The code bellow shows how to configure a distributable cache store that uses Infinispan:

ConfigurationBuilder builder = new ConfigurationBuilder();

builder
    .sessionManager()
        .store(new DistributableSessionStore(ISPN_CONFIG_PATH))
        .sessionTimeout(1);

// more config

Distributable/Infinispan Session Store

To distribute or replicate the sessions between different instances of your application you can use the org.picketbox.infinispan.session.store.DistributableSessionStore.

This implementation uses Infinispan's caches to manage your sessions. To use this implementation your need to add the following dependency to your project:

<dependency>
    <groupId>org.picketbox</groupId>
    <artifactId>picketbox-infinispan</artifactId>
    <version>${picketbox.version}</version>
</dependency>

You can see a simple working example here https://github.com/picketbox/picketbox/blob/master/infinispan/src/test/java/org/picketbox/test/infinispan/session/store/InfinispanSessionStoreTestCase.java.

Where sessions are located after an user is authenticated ?

After the user is authenticated and its session is created, PicketBox will retain a reference for the session inside the subject. The code bellow shows how to retrieve the session from the subject:

PicketBoxSubject subject = firstPicketBoxManager.authenticate(subject);
PicketBoxSession session = originalSubject.getSession();

Working with session attributes

The PicketBoxSession allows you to handle session attributes. Some methods are provided for that:

session.setAttribute("attributeA", "attributeA");
session.getAttribute("attributeA")

Handling events

You can also configure listeners for some specific session relataed events like: creation, expiration, invalidation, etc.

ConfigurationBuilder builder = new ConfigurationBuilder();

builder.sessionManager().listener(new CustomSessionListener());

Session listeners must implement the interface org.picketbox.core.session.PicketBoxSessionListener.

Simple way to create sessions without Builder

PicketBoxSession session = PicketBoxSessionManager.create();